Skip to content

[MRG] Fix batched envelope gradients with respect to marginals - #926

Open
xihaian251 wants to merge 1 commit into
PythonOT:masterfrom
xihaian251:fix/batched-envelope-marginal-gradients
Open

xihaian251 wants to merge 1 commit into
PythonOT:masterfrom
xihaian251:fix/batched-envelope-marginal-gradients

Conversation

@xihaian251

Copy link
Copy Markdown
Contributor

Types of changes

  • Bug fix (non-breaking change which fixes an issue)

Motivation and context / Related issue

solve_batch(..., grad="envelope") detaches the transport plan T before evaluating the objective. The returned value therefore keeps a differentiable path to the cost matrix M (so grad_M = P* is correct), but the marginals a and b only enter through the detached solver. With entropy regularization their gradient was None; with KL regularization the only surviving term was an incorrect one coming from the reference measure a (x) b.

Minimal reproducer (M = 0, reg = 1, method="log_sinkhorn", grad="envelope", torch.float64, a=(p, 1-p), b=(1/2, 1/2), p=3/4):

quantity before this PR expected
value -1.2554823251787532 -1.2554823251787537 (Wolfram)
grad_M P* P* (already correct)
grad_p None log 3 = 1.0986122886681097

The same defect affects a second marginal: with b=(q, 1/3, 2/3-q) and q=1/2, dF/dq = log 3, which the pre-fix API also failed to provide. The non-batched ot.solve(..., grad="envelope") already registers the correct sensitivities grad_a = reg * (u - mean(u)) and grad_b = reg * (v - mean(v)) through nx.set_gradients. That helper implements a scalar-output VJP and is not valid for the (B,) vector value returned by solve_batch: we verified a silent mis-broadcast at B=2 and a shape error at B=3. This PR therefore adds a local, batch-aware autograd Function instead of changing the global backend API.

How has this been tested (if it applies)

  • Real-API negative controls: B=1 and B=2/3/8. Before the fix, grad_p was None while grad_M = w_b P_b* was already correct; after the fix both marginal and cost gradients match the analytic values.
  • Dual-marginal analytic test: a=(p,1-p), b=(q,1/3,2/3-q), M=0, reg=1, p=3/4, q=1/2. A single torch.autograd.grad call checks grad_p = grad_q = w * log 3, together with shape, dtype, device and upstream-cotangent scaling.
  • Independent oracles: Wolfram symbolic derivatives and mass-conserving central differences agree with the implemented VJP for entropy and KL, across log_sinkhorn, sinkhorn and proximal, float32/float64 and near-zero marginals. The explicit -reg log(a) KL reference term is included, and the proximal effective coefficient is reg + inner_reg.
  • Optional dependency: in fresh processes with POT_BACKEND_DISABLE_PYTORCH=1, import ot, import ot.batch and NumPy solve_batch (entropy/KL, envelope/detach/autodiff) all succeed, with no False.autograd or undefined-class errors.
  • Targeted regression: pytest -q test/batch/ — 132 passed, 3 pre-existing warnings. Ruff 0.5.2 (the version pinned by pre-commit) and git diff --check are clean.
  • Broader local run: with two environment-limited files excluded, pytest -q test/ --ignore=test/test_bspot.py --ignore=test/test_helpers.py gave 3614 passed, 468 skipped, 6 xfailed, exit code 0. The two exclusions are documented limitations, not passing tests: (1) the locally available BSP native extension was compiled from a different source revision than this master, causing a segfault in test/test_bspot.py; (2) the sandbox blocks reg.exe, so MSVC cannot probe the Windows SDK and test/test_helpers.py fails at compiler detection. We did not bypass the security policy, and we do not claim the unmodified full suite is green. Upstream CI has not run yet for this PR.

PR checklist

  • I have read the CONTRIBUTING document.
  • The documentation is up-to-date with the changes I made (check build artifacts).
  • All tests that can be run in this environment passed, and additional code has been covered with new tests.
  • I have added the PR and Issue fix to the RELEASES.md file.

Scope note

The change is local to ot/batch/_linear.py and applies to PyTorch only. It preserves the existing M gradient path and the forward value and plan bit-for-bit, and leaves JAX/TensorFlow behaviour unchanged. The custom marginal gradient is first-order only; higher-order differentiation, JAX/TensorFlow batch marginal gradients and solve_gromov_batch envelope gradients are explicitly out of scope.

@codecov

codecov Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.10%. Comparing base (7d51e72) to head (1a0b5ce).

Additional details and impacted files
@@            Coverage Diff             @@
##           master     #926      +/-   ##
==========================================
+ Coverage   97.09%   97.10%   +0.01%     
==========================================
  Files         130      130              
  Lines       27229    27336     +107     
==========================================
+ Hits        26437    26544     +107     
  Misses        792      792              
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant